home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 025a / bk5a1rep.zip / SORTF.DOC < prev    next >
Text File  |  1989-02-18  |  10KB  |  335 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                  SORTF Command
  11.  
  12.               Version 2.32 - Feb 18, 1989
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                      Index
  19.                      -----
  20.  
  21.  
  22.          Purpose  ................................... 1
  23.           Format  ................................... 1
  24.           Remarks  ...................................1
  25.  
  26.          Options summary  ........................... 2
  27.          Invoking from Quick Basic................... 2
  28.  
  29.          Examples  .................................. 3
  30.  
  31.          Version history  ........................... 4
  32.  
  33.          Usage restrictions  ........................ 5
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.       Copyright (c) Vernon D. Buerg 1985-89. ALL RIGHTS RESERVED.
  54.  
  55.  
  56.  
  57. SORTF Command                          Version 2.32    Page 1
  58. -------------                          Feb 18, 1989
  59.  
  60.  
  61. Purpose:   The SORTF command reads record data from a file,  sorts the
  62.        records, and writes the data to another file.
  63.  
  64. Format:
  65.        SORTF [d:][path]fname[.ext] [d:][path]fname[.ext]
  66.          [/+nnn[,len]] -or- [/-nnn,[len]]
  67.          [/Lnnn]
  68.          [/R] [/C] [/Q]
  69. |         [/K] or [/X]
  70.  
  71. Remarks:   Records are read from the input file,  sorted,  and written
  72.        to the output file.
  73.  
  74.        Two types of records may be sorted:
  75.  
  76.        1)  logical    records.   Each  record  ends  with a carriage
  77.            return and line feed, and  may be up to 1024 characters
  78.            in length.
  79.  
  80.        2)  fixed length  records.  Each record  is of length  L as
  81.            defined    by  the  '/Lnnn'  parameter.   The records may
  82.            contain any  kind of  data, including  carriage return,
  83.            line feed, and end-of-file without effecting the record
  84.            length. The maximum record is 1024 bytes.
  85.  
  86.  
  87.        The sort  order is  in ascending  ASCII character sequence.
  88.        You may supply the /R  parameter to reverse the sort  order
  89.        for all fields, or supply /- parameters for each key  field
  90.        to  be  sorted  in  reverse    order.     The  key  fields  are
  91.        processed from  left to  right as  supplied in  the command
  92.        line.
  93.  
  94.        The /C option may be added to cause SORTF to treat the  key
  95.        fields  as  case  insensitive  data.   That    is, lower case
  96.        letters in the key field are treated as upper case letters.
  97.  
  98.        You may  supply up  to sixteen  key offsets    and lengths by
  99.        using the /+ or /- parameter, one for each key position and
  100.        its length.     If /+    and /-    are omitted,  the key is taken
  101.        from the first character position for a length of 11.
  102.  
  103.        The position 'nnn' may be a value from one to 255.
  104.  
  105.        The key length 'len' may be  a value from 1 to 99.   The /+
  106.        operand  specifies  that  the  specified  key  is sorted in
  107.        ascending order.  The /- specifies desending sort order for
  108.        that key.
  109.  
  110.        Use the /Q option to suppress the display of  informational
  111.        messages.  Error messages can not be suppressed.
  112.  
  113.  
  114. SORTF Command                          Version 2.32    Page 2
  115. -------------                          Feb 18, 1989
  116.  
  117.             Options Summary
  118.             ---------------
  119.  
  120.  
  121.        /C  specifies  that    the  keys  are    case  insensitive;  if
  122.            supplied, all lower case  characters in the key    fields
  123.            are  converted  to  upper  case    for  the  purposes  of
  124.            sorting.
  125.  
  126.        /R  sort in    reverse order;    over-rides any    /- options and
  127.            treats them all as /+ options.
  128.  
  129.        /Q  suppress informational messages.
  130.  
  131.  
  132.        /K  creates an output file that consists of sorted key data
  133.            which includes a 5-byte information prefix.
  134.  
  135. |       /X  like /K, except that the 5-byte information prefix is
  136. |           omitted, and a cr/lf (carriage return and line feed)
  137. |           is added to each record.
  138.  
  139.  
  140.        /L  specifies the sorting of fixed length records
  141.  
  142.        /+  defines the location  and length of  a key field  to be
  143.            sorted in ascending order
  144.  
  145.        /-  defines the location  and length of  a key field  to be
  146.            sorted in descending order
  147.  
  148.  
  149.  
  150.  
  151.             Invoking from Quick Basic
  152.             -------------------------
  153.  
  154.     To invoke SORTF from a Quick Basic program, you can use either
  155.     the SHELL or CALL statements.  Use of SHELL is straightforward.
  156.     Use of CALL requires that you include SORTF.OBJ when you LINK
  157.     your QB program, and that you use the /CP LINK option to ensure
  158.     that memory is available for SORTF. For example:
  159.  
  160.     in the QB program : CALL SORTF ("test.fil new.fil /+1,12")
  161.              -or-   SHELL "sortf test.fil new.fil /+1,12"
  162.  
  163.     for CALL:        LINK qbprogram + SORTF /CP:5000;
  164.  
  165.     The /CP:5000 option will limit the QB program to 80K plus the
  166.     size of its code, data and stack. Whatever is left can be used
  167.     by CALLed programs. That amount will be about 120K less than
  168.     the DOS available memory.
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175. SORTF Command                          Version 2.32    Page 3
  176. -------------                          Feb 18, 1989
  177.  
  178.             Examples
  179.             --------
  180.  
  181.      o  to    sort  a  file  in  descending order with the keys in
  182.        position 10:
  183.  
  184.         SORTF TEST.DAT TEST.SRT /R/+10
  185.  
  186.      o  to sort the same file using keys with 24 characters:
  187.  
  188.         SORTF TEST.DAT TEST.SRT /R/+10,24
  189.  
  190.      o  to sort a file of fixed length, binary records; the input
  191.        file contains records of 18 bytes each,  the  key is  two
  192.        bytes  at  position    17  in    each  record  in  descending
  193.        order, and 11 bytes at postion 1 in ascending order:
  194.  
  195.         SORTF SRTCATS.RND SRTCATS.IND /L18 /-17,2 /+1,12
  196.  
  197.      o  to sort on different keys, but creating an an output file
  198.        with the keys only:
  199.  
  200.         SORTF TEST.DAT TEST.KEYS /-10,2 /+20,4 /-16,3 /K
  201.  
  202.        Note the use of /-.    It specifies that the first and  third
  203.        keys  are  sorted  in  descending  order, the second key is
  204.        sorted in ascending order.
  205.  
  206.        The format of the keys-only file using /K is:
  207.  
  208.        Offset  Length   Contents
  209.        ------  ------   ------------------------------------------
  210.          0         2        Length of data record excluding CR and LF
  211.          2         3        Offset to record in input file
  212.                  +0  hi-byte of 3-byte address offset
  213.                  +1  low word of address offset
  214.          5         n        Variable key data, depends on key definitions
  215.  
  216. |       The format of the keys-only file using /X is:
  217. |
  218. |       Offset  Length   Contents
  219. |       ------  ------   ------------------------------------------
  220. |         0         n        Variable key data, depends on key definitions
  221. |         n         2        Carriage return and line feed
  222.  
  223.        In the example above, the variable key data format is:
  224.  
  225.          5         2        Data in records at offset 10
  226.          7         4        Data in records at offset 20
  227.         11         3        Data in records at offset 16
  228.         14         0        End of key record.
  229.  
  230.        The length of  each keys-only record  is 5 plus  the sum of
  231.        the individual key lengths.    The default, if no /+ or /- is
  232.        specified, is 16 bytes each.
  233.  
  234.  
  235. SORTF Command                          Version 2.32    Page 4
  236. -------------                          Feb 18, 1989
  237.  
  238.             Version History
  239.             ---------------
  240.  
  241.  2.0, July 11, 1985.  Corrects CR/LF problem.
  242.  
  243.  2.1, August 3, 1985. Corrects a problem sorting files larger than 64K.
  244.  
  245.  2.15, Dec 27, 1985.  Corrects problems with first record of file.
  246.               Adds /C option to treat keys as case insensitive data
  247.               The key length may be specified on the command line
  248.  
  249.  2.17, Feb 25, 1987.  Correct problem when maximum records exceeded
  250.               Convert to COM program
  251.  
  252.  2.20, June 28, 1987. Add /Q option to suppress informational messages
  253.               Change to allow up to 16 key field specifications
  254.  
  255.  2.23, Aug 6, 1987.   Add "-" option to sort individual fields in reverse order
  256.               Add /K option to produce output file with keys only
  257.  
  258.  2.24, Sep 15, 1987.  Add /Lnnn option for sorting fixed length records
  259.  
  260.  2.25, Sep 19, 1987.  Correction for /L dropping last char of file and fouling
  261.               records.
  262.  
  263.  2.26, Dec 16, 1987.  Cosmetic changes
  264.  
  265.  2.27, Feb 1, 1988.   Fix divide overflow on large files; terminate with
  266.               message "Maximum records exceeded"
  267.  
  268.  2.29, March 5, 1988. Release gotten memory
  269.               Add SORTF entry point for CALL from Quick Basic
  270.  
  271.  2.30, May 23, 1988.  Change maximum record size from 255 to 1023
  272.               Change default key length from 12 to 11
  273.  
  274. |2.31, Feb 16, 1989.  Add /X option like /K to write file with keys only,
  275. |              and a cr/lf at the end of each record.
  276.  
  277. |2.32, Feb 18, 1989.  Correct problem LINKing with QB 4.5
  278.  
  279.  
  280. SORTF Command                          Version 2.32    Page 5
  281. -------------                          Feb 18, 1989
  282.  
  283.             Restrictions
  284.             ------------
  285.  
  286.        Depending on the amount of  memory available,  up to  40000
  287.        records may be sorted.  The maximum file  size that    can be
  288.        sorted depends  on the  maximum number  of records  and the
  289.        average record  length.  For  example,  the    file  size  is
  290.        limited to 3.2 mb for a file consisting of 80-byte records.
  291.  
  292.  
  293.        The advantages of using  SORTF  instead of the SORT filter:
  294.         - files larger than 63K may be sorted
  295.         - less time is required
  296.         - sort order can be based on up to 16 fields
  297.         - fixed length files can be sorted
  298.  
  299.        For    best  results,    place the  input file  on the  fastest
  300.        available drive, e.g. RAM disk.
  301.  
  302.  
  303.  
  304.        Written by  Vernon Buerg  for the  IBM PC  using DOS 2.0 or
  305.        later.  You may distribute SORTF given these restrictions:
  306.  
  307.        o  the program shall be supplied in its original, unmodified
  308.           form, which includes this documentation;
  309.  
  310.        o  no fee is charged;
  311.  
  312.        o  for-profit use without a license is prohibited;
  313.  
  314.        o  the program may not  be included, or bundled, with  other
  315.           goods  or  services.   Exceptions  may  be  granted  upon
  316.           written  request    only. This  also applies to  clubs  and
  317.           distributors.
  318.  
  319.  
  320.        For use by corporations and other institutions, contact  me
  321.        for a licensing agreement.
  322.  
  323.        If you find SORTF useful, your gift of $15,    or any amount,
  324.        would be greatly appreciated.
  325.  
  326.  
  327.         Vernon D. Buerg
  328.         139 White Oak Circle
  329.         Petaluma, CA  94952
  330.  
  331.         Data: (707) 778-8944, 24-hour BBS
  332.         CompuServe: 70007,1212
  333.  
  334.  
  335.